<?xml version="1.0" encoding="ascii" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ascii" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Regression Testing for epydoc.docparser</title>
<link rel="stylesheet" href="../custom.css" type="text/css" />
</head>
<body>
<div class="document" id="regression-testing-for-epydoc-docparser">
<h1 class="title">Regression Testing for epydoc.docparser</h1>

<p>The <cite>epydoc.docparser</cite> module is used to extract API documentation by
parsing the source code of Python files.  Its primary interface is
<cite>docparser.parse_docs()</cite>, which takes a module's filename, and returns a
ModuleDoc describing that module and its contents.</p>
<div class="section" id="test-function">
<h1>Test Function</h1>
<p>This test function takes a string containing the contents of a module,
and writes it to a file, uses <cite>docparser.parse_docs()</cite> to parse it, and pretty
prints the resulting ModuleDoc object.  The <tt class="docutils literal"><span class="pre">attribs</span></tt> argument
specifies which attributes of the <cite>APIDoc`s should be displayed.  The
``show`</cite> argument, if specifies, gives the name of the object in the
module that should be displayed (but the whole module will always be
inspected; this just selects what to display).</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> epydoc.test.util <span class="py-keyword">import</span> runparser</pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> epydoc.test.util <span class="py-keyword">import</span> print_warnings
<span class="py-prompt">&gt;&gt;&gt; </span>print_warnings()</pre>
</blockquote>
</div>
<div class="section" id="module-variables-from-assignment-statements">
<h1>Module Variables from Assignment Statements</h1>
<p>Variables are extracted from any assignment statements in the module,
including statements contained inside of top-level if statements, for
loops, while loops, and try/except/finally blocks.  Tuple assignments
are unpacked, when possible.</p>
<p>For simple variable assignments, DocParser creates <cite>VariableDoc</cite> objects
containing the name; a valuedoc with the value (as both an abstract
syntax tree and a string representation); and information about
whether we think the value was imported; is an alias; and is an
instance variable.  (For variables generated from module variable
assignments, is_imported and is_instvar will always be False.)</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = 12</span>
<span class="py-more">... </span><span class="py-string">    y = [1,2,3] + [4,5]</span>
<span class="py-more">... </span><span class="py-string">    z = f(x,y)</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- canonical_name = DottedName('epydoc_test')</span>
<span class="py-output"> +- defining_module</span>
<span class="py-output"> |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output"> +- docs_extracted_by = 'parser'</span>
<span class="py-output"> +- filename = ...</span>
<span class="py-output"> +- imports = []</span>
<span class="py-output"> +- is_package = False</span>
<span class="py-output"> +- package = None</span>
<span class="py-output"> +- sort_spec = [u'x', u'y', u'z']</span>
<span class="py-output"> +- submodules = []</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">    |  +- container</span>
<span class="py-output">    |  |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">    |  +- docs_extracted_by = 'parser'</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- is_imported = False</span>
<span class="py-output">    |  +- is_instvar = False</span>
<span class="py-output">    |  +- is_public = True</span>
<span class="py-output">    |  +- name = u'x'</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- GenericValueDoc [2]</span>
<span class="py-output">    |        +- defining_module</span>
<span class="py-output">    |        |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">    |        +- docs_extracted_by = 'parser'</span>
<span class="py-output">    |        +- parse_repr = u'12'</span>
<span class="py-output">    |        +- toktree = [(2, u'12')]</span>
<span class="py-output">    +- y =&gt; VariableDoc for epydoc_test.y [3]</span>
<span class="py-output">    |  +- container</span>
<span class="py-output">    |  |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">    |  +- docs_extracted_by = 'parser'</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- is_imported = False</span>
<span class="py-output">    |  +- is_instvar = False</span>
<span class="py-output">    |  +- is_public = True</span>
<span class="py-output">    |  +- name = u'y'</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- GenericValueDoc [4]</span>
<span class="py-output">    |        +- defining_module</span>
<span class="py-output">    |        |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">    |        +- docs_extracted_by = 'parser'</span>
<span class="py-output">    |        +- parse_repr = u'[1, 2, 3]+ [4, 5]'</span>
<span class="py-output">    |        +- toktree = ...</span>
<span class="py-output">    +- z =&gt; VariableDoc for epydoc_test.z [5]</span>
<span class="py-output">       +- container</span>
<span class="py-output">       |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">       +- docs_extracted_by = 'parser'</span>
<span class="py-output">       +- is_alias = False</span>
<span class="py-output">       +- is_imported = False</span>
<span class="py-output">       +- is_instvar = False</span>
<span class="py-output">       +- is_public = True</span>
<span class="py-output">       +- name = u'z'</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- GenericValueDoc [6]</span>
<span class="py-output">             +- defining_module</span>
<span class="py-output">             |  +- ModuleDoc for epydoc_test [0] (defined above)</span>
<span class="py-output">             +- docs_extracted_by = 'parser'</span>
<span class="py-output">             +- parse_repr = u'f(x, y)'</span>
<span class="py-output">             +- toktree = ...</span></pre>
</blockquote>
<p>In this example, DocParser decides that the assignment to y is
creating an alias.  The same <cite>ValueDoc</cite> is shared by both variables.</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = [1,2]</span>
<span class="py-more">... </span><span class="py-string">    y = x</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables is_alias name value parse_repr'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- parse_repr = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'x'</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- GenericValueDoc [2]</span>
<span class="py-output">    |        +- parse_repr = u'[1, 2]'</span>
<span class="py-output">    +- y =&gt; VariableDoc for epydoc_test.y [3]</span>
<span class="py-output">       +- is_alias = True</span>
<span class="py-output">       +- name = u'y'</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- GenericValueDoc [2] (defined above)</span></pre>
</blockquote>
<p>DocParser can also parse assignments where the left-hand side is a
tuple or list; however, it will not extract values.</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    a,b = (5,6)</span>
<span class="py-more">... </span><span class="py-string">    [a,(b,[c,d],e),(f,g)] = [1,(2,[3,4],5),(6,7)]</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables is_alias name value'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- a =&gt; VariableDoc for epydoc_test.a [1]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'a'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- b =&gt; VariableDoc for epydoc_test.b [2]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'b'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- c =&gt; VariableDoc for epydoc_test.c [3]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'c'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- d =&gt; VariableDoc for epydoc_test.d [4]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'd'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- e =&gt; VariableDoc for epydoc_test.e [5]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'e'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- f =&gt; VariableDoc for epydoc_test.f [6]</span>
<span class="py-output">    |  +- is_alias = False</span>
<span class="py-output">    |  +- name = u'f'</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- g =&gt; VariableDoc for epydoc_test.g [7]</span>
<span class="py-output">       +- is_alias = False</span>
<span class="py-output">       +- name = u'g'</span>
<span class="py-output">       +- value = &lt;UNKNOWN&gt;</span></pre>
</blockquote>
<p>DocParser can also parse 'multi-assignment' statements, containing
more than one assignment.  Note that the ValueDoc object is shared;
and all but the rightmost variable are marked as aliases.  (As a
result, the value's canonical name will use the name of the rightmost
variable.)</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = y = z = 0</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables is_alias name value parse_repr&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- parse_repr = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">    |  +- is_alias = True</span>
<span class="py-output">    |  +- name = u'x'</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- GenericValueDoc [2]</span>
<span class="py-output">    |        +- parse_repr = u'0'</span>
<span class="py-output">    +- y =&gt; VariableDoc for epydoc_test.y [3]</span>
<span class="py-output">    |  +- is_alias = True</span>
<span class="py-output">    |  +- name = u'y'</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- GenericValueDoc [2] (defined above)</span>
<span class="py-output">    +- z =&gt; VariableDoc for epydoc_test.z [4]</span>
<span class="py-output">       +- is_alias = False</span>
<span class="py-output">       +- name = u'z'</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- GenericValueDoc [2] (defined above)</span></pre>
</blockquote>
<p>If a variable is assigned to twice, then the later assignment
overwrites the earlier one:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = 22</span>
<span class="py-more">... </span><span class="py-string">    x = 33</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name value parse_repr&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- parse_repr = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- name = u'x'</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- GenericValueDoc [2]</span>
<span class="py-output">             +- parse_repr = u'33'</span></pre>
</blockquote>
<p>Some class variable have a special meaning. The <tt class="docutils literal"><span class="pre">__slots__</span></tt> variable isn't
very useful and should be discarded.</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class Foo:</span>
<span class="py-more">... </span><span class="py-string">        __slots__ = ['bar']</span>
<span class="py-more">... </span><span class="py-string">        def __init__(self):</span>
<span class="py-more">... </span><span class="py-string">            self.bar = 0</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name value&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- Foo =&gt; VariableDoc for epydoc_test.Foo [1]</span>
<span class="py-output">       +- name = u'Foo'</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.Foo [2]</span>
<span class="py-output">             +- variables</span>
<span class="py-output">                +- __init__ =&gt; VariableDoc for epydoc_test.Foo.__init__ [3]</span>
<span class="py-output">                   +- name = u'__init__'</span>
<span class="py-output">                   +- value</span>
<span class="py-output">                      +- RoutineDoc for epydoc_test.Foo.__init__ [4]</span></pre>
</blockquote>
</div>
<div class="section" id="module-control-blocks">
<h1>Module Control Blocks</h1>
<p>DocParser will look inside certain types of module-level control
blocks.  By default, DocParser looks inside the following block types:</p>
<ul class="simple">
<li>if blocks</li>
<li>elif blocks</li>
<li>else blocks</li>
<li>try blocks</li>
<li>except blocks</li>
<li>finally blocks</li>
</ul>
<p>By default, DocParse does not look inside the following block types:</p>
<ul>
<li><p class="first">while blocks</p>
</li>
<li><p class="first">for blocks</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-comment"># DocParser looks inside if/elif/else blocks.</span>
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    if condition:</span>
<span class="py-more">... </span><span class="py-string">        if_gated = 'x'</span>
<span class="py-more">... </span><span class="py-string">    elif condition2:</span>
<span class="py-more">... </span><span class="py-string">        elif_gated = 'y'</span>
<span class="py-more">... </span><span class="py-string">    elif condition3:</span>
<span class="py-more">... </span><span class="py-string">        elif_gated2 = 'x'</span>
<span class="py-more">... </span><span class="py-string">    else:</span>
<span class="py-more">... </span><span class="py-string">        else_gated = 'z'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- elif_gated =&gt; VariableDoc for epydoc_test.elif_gated [1]</span>
<span class="py-output">    |  +- name = u'elif_gated'</span>
<span class="py-output">    +- elif_gated2 =&gt; VariableDoc for epydoc_test.elif_gated2 [2]</span>
<span class="py-output">    |  +- name = u'elif_gated2'</span>
<span class="py-output">    +- else_gated =&gt; VariableDoc for epydoc_test.else_gated [3]</span>
<span class="py-output">    |  +- name = u'else_gated'</span>
<span class="py-output">    +- if_gated =&gt; VariableDoc for epydoc_test.if_gated [4]</span>
<span class="py-output">       +- name = u'if_gated'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-comment"># DocParser looks inside try/except and try/finally blocks:</span>
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    try:</span>
<span class="py-more">... </span><span class="py-string">        try:</span>
<span class="py-more">... </span><span class="py-string">            try_gated = 'x'</span>
<span class="py-more">... </span><span class="py-string">        except Exception1:</span>
<span class="py-more">... </span><span class="py-string">            except_gated = 'x'</span>
<span class="py-more">... </span><span class="py-string">        except:</span>
<span class="py-more">... </span><span class="py-string">            except_gated2 = 'y'</span>
<span class="py-more">... </span><span class="py-string">    finally:</span>
<span class="py-more">... </span><span class="py-string">        finally_gated = 'z'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- except_gated =&gt; VariableDoc for epydoc_test.except_gated [1]</span>
<span class="py-output">    |  +- name = u'except_gated'</span>
<span class="py-output">    +- except_gated2 =&gt; VariableDoc for epydoc_test.except_gated2 [2]</span>
<span class="py-output">    |  +- name = u'except_gated2'</span>
<span class="py-output">    +- finally_gated =&gt; VariableDoc for epydoc_test.finally_gated [3]</span>
<span class="py-output">    |  +- name = u'finally_gated'</span>
<span class="py-output">    +- try_gated =&gt; VariableDoc for epydoc_test.try_gated [4]</span>
<span class="py-output">       +- name = u'try_gated'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-comment"># By default, DocParser does not look inside for blocks</span>
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    for itervar in [5]*3:</span>
<span class="py-more">... </span><span class="py-string">        for_gated = 'x'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables = {}</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-comment"># By default, DocParser does not look inside while blocks</span>
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    while condition:</span>
<span class="py-more">... </span><span class="py-string">        while_gated = 'x'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables = {}</span></pre>
</blockquote>
</li>
</ul>
<p>The set of blocks that DocParser looks inside are controlled by a set
of global variables in <cite>epydoc.docparser</cite>.  For example, the following
code creates a DocParser that does look inside for blocks and while
blocks:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">import</span> epydoc.docparser
<span class="py-prompt">&gt;&gt;&gt; </span>epydoc.docparser.PARSE_FOR_BLOCKS = True
<span class="py-prompt">&gt;&gt;&gt; </span>epydoc.docparser.PARSE_WHILE_BLOCKS = True
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    for itervar in [5]*3:</span>
<span class="py-more">... </span><span class="py-string">        for_gated = 'x'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- for_gated =&gt; VariableDoc for epydoc_test.for_gated [1]</span>
<span class="py-output">    |  +- name = u'for_gated'</span>
<span class="py-output">    +- itervar =&gt; VariableDoc for epydoc_test.itervar [2]</span>
<span class="py-output">       +- name = u'itervar'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    while condition:</span>
<span class="py-more">... </span><span class="py-string">        while_gated = 'x'&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- while_gated =&gt; VariableDoc for epydoc_test.while_gated [1]</span>
<span class="py-output">       +- name = u'while_gated'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-comment"># reset the globals:</span>
<span class="py-prompt">&gt;&gt;&gt; </span>reload(epydoc.docparser) <span class="py-keyword">and</span> None</pre>
</blockquote>
<p>Note that when DocParser examines a for block, it also creates a
VariableDoc for the loop variable (itervar in this case).</p>
</div>
<div class="section" id="variable-docstrings">
<h1>Variable Docstrings</h1>
<p>The DocParser can extract docstrings for variables.  These docstrings
can come from one of two places: string constants that immediately
follow the assignment statement; or comments starting with the special
sequence &quot;#:&quot; that occur before the assignment or on the same line as
it.</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = 12</span>
<span class="py-more">... </span><span class="py-string">    '''docstring for x.</span>
<span class="py-more">... </span><span class="py-string">    (can be multiline)'''&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name docstring&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- docstring = u'docstring for x.\n(can be multiline)'</span>
<span class="py-output">       +- name = u'x'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = 12 #: comment docstring for x&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name docstring&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- docstring = u'comment docstring for x'</span>
<span class="py-output">       +- name = u'x'</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    #: comment docstring for x.</span>
<span class="py-more">... </span><span class="py-string">    #: (can be multiline)</span>
<span class="py-more">... </span><span class="py-string">    x = 12&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name docstring&quot;</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- docstring = u'comment docstring for x.\n(can be m...</span>
<span class="py-output">       +- name = u'x'</span></pre>
</blockquote>
<p>If comments and a string constant are both used, then the string
constant takes precedence:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    #: comment1</span>
<span class="py-more">... </span><span class="py-string">    x = 12 #: comment2</span>
<span class="py-more">... </span><span class="py-string">    '''string'''&quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">&quot;variables name docstring&quot;</span>)
<span class="py-output">&lt;UNKNOWN&gt; has both a comment-docstring and a normal (string) docstring; ignoring the comment-docstring.</span>
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- docstring = u'string'</span>
<span class="py-output">       +- name = u'x'</span></pre>
</blockquote>
</div>
<div class="section" id="functions">
<h1>Functions</h1>
<p>When DocParser encounters a function definition statement, it creates
a corresponding FunctionDoc object (as the valuedoc attribute of a
VariableDoc object in the module's children list).</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    def f(x):</span>
<span class="py-more">... </span><span class="py-string">        'docstring for f'</span>
<span class="py-more">... </span><span class="py-string">        print 'inside f'</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>, show=<span class="py-string">&quot;f&quot;</span>, exclude=<span class="py-string">'defining_module'</span>)
<span class="py-output">RoutineDoc for epydoc_test.f [0]</span>
<span class="py-output"> +- canonical_name = DottedName('epydoc_test', u'f')</span>
<span class="py-output"> +- decorators = []</span>
<span class="py-output"> +- docs_extracted_by = 'parser'</span>
<span class="py-output"> +- docstring = u'docstring for f'</span>
<span class="py-output"> +- docstring_lineno = 3</span>
<span class="py-output"> +- kwarg = None</span>
<span class="py-output"> +- lineno = 2</span>
<span class="py-output"> +- posarg_defaults = [None]</span>
<span class="py-output"> +- posargs = [u'x']</span>
<span class="py-output"> +- vararg = None</span></pre>
</blockquote>
<p>The function's arguments are described by the properties <tt class="docutils literal"><span class="pre">posargs</span></tt>,
<tt class="docutils literal"><span class="pre">posarg_defaults</span></tt>, <tt class="docutils literal"><span class="pre">kwarg</span></tt>, and <tt class="docutils literal"><span class="pre">vararg</span></tt>.  <tt class="docutils literal"><span class="pre">posargs</span></tt> is a list of
argument names (or nested tuples of names, for tuple-unpacking args).
<tt class="docutils literal"><span class="pre">posarg_defaults</span></tt> is a list of <cite>ValueDoc</cite>s for default values,
corresponding 1:1 with <tt class="docutils literal"><span class="pre">posargs</span></tt>.  <tt class="docutils literal"><span class="pre">posarg_defaults</span></tt> is None for
arguments with no default value.  <tt class="docutils literal"><span class="pre">vararg</span></tt> and <tt class="docutils literal"><span class="pre">kwarg</span></tt> are the names
of the variable argument and keyword argument, respectively:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    def f(x, y=22, z=(1,), *v, **kw):</span>
<span class="py-more">... </span><span class="py-string">        'docstring for f'</span>
<span class="py-more">... </span><span class="py-string">        print 'inside f'</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>, show=<span class="py-string">&quot;f&quot;</span>, exclude=<span class="py-string">'defining_module'</span>)
<span class="py-output">RoutineDoc for epydoc_test.f [0]</span>
<span class="py-output"> +- canonical_name = DottedName('epydoc_test', u'f')</span>
<span class="py-output"> +- decorators = []</span>
<span class="py-output"> +- docs_extracted_by = 'parser'</span>
<span class="py-output"> +- docstring = u'docstring for f'</span>
<span class="py-output"> +- docstring_lineno = 3</span>
<span class="py-output"> +- kwarg = u'kw'</span>
<span class="py-output"> +- lineno = 2</span>
<span class="py-output"> +- posarg_defaults = [None, &lt;GenericValueDoc None&gt;, &lt;Gener...</span>
<span class="py-output"> +- posargs = [u'x', u'y', u'z']</span>
<span class="py-output"> +- vararg = u'v'</span></pre>
</blockquote>
<dl class="docutils">
<dt>Tuple arguments are encoded as a single ArgDoc with a complex name:</dt>
<dd><pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    def f( (x, (y,z)) ): pass</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>, show=<span class="py-string">&quot;f&quot;</span>, exclude=<span class="py-string">'defining_module'</span>)
<span class="py-output">RoutineDoc for epydoc_test.f [0]</span>
<span class="py-output"> +- canonical_name = DottedName('epydoc_test', u'f')</span>
<span class="py-output"> +- decorators = []</span>
<span class="py-output"> +- docs_extracted_by = 'parser'</span>
<span class="py-output"> +- kwarg = None</span>
<span class="py-output"> +- lineno = 2</span>
<span class="py-output"> +- posarg_defaults = [None]</span>
<span class="py-output"> +- posargs = [[u'x', [u'y', u'z']]]</span>
<span class="py-output"> +- vararg = None</span></pre>
</dd>
</dl>
</div>
<div class="section" id="decorators-wrapper-assignments">
<h1>Decorators &amp; Wrapper Assignments</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser( <span class="py-comment"># doctest: +PYTHON2.4</span>
<span class="py-more">... </span>    s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    @classmethod</span>
<span class="py-more">... </span><span class="py-string">    def f(cls, x): 'docstring for f'</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value docstring posargs'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- f =&gt; VariableDoc for epydoc_test.f [1]</span>
<span class="py-output">       +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassMethodDoc for epydoc_test.f [2]</span>
<span class="py-output">             +- docstring = u'docstring for f'</span>
<span class="py-output">             +- posargs = [u'cls', u'x']</span></pre>
</blockquote>
</div>
<div class="section" id="classes">
<h1>Classes</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class A:</span>
<span class="py-more">... </span><span class="py-string">        &quot;no bases&quot;</span>
<span class="py-more">... </span><span class="py-string">        class Nested: &quot;nested class&quot;</span>
<span class="py-more">... </span><span class="py-string">    class B(A): &quot;single base&quot;</span>
<span class="py-more">... </span><span class="py-string">    class C(A,B): &quot;multiple bases&quot;</span>
<span class="py-more">... </span><span class="py-string">    class D( ((A)) ): &quot;extra parens around base&quot;</span>
<span class="py-more">... </span><span class="py-string">    class E(A.Nested): &quot;dotted name&quot;</span>
<span class="py-more">... </span><span class="py-string">    class F(((A).Nested)): &quot;parens with dotted name&quot;</span>
<span class="py-more">... </span><span class="py-string">    class Z(B.__bases__[0]): &quot;calculated base&quot; # not handled!</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value bases docstring'</span>)
<span class="py-output">Unable to extract the base list for epydoc_test.Z: Bad dotted name</span>
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- A =&gt; VariableDoc for epydoc_test.A [1]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.A [2]</span>
<span class="py-output">    |        +- bases = []</span>
<span class="py-output">    |        +- docstring = u'no bases'</span>
<span class="py-output">    |        +- variables</span>
<span class="py-output">    |           +- Nested =&gt; VariableDoc for epydoc_test.A.Nested [3]</span>
<span class="py-output">    |              +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |              +- value</span>
<span class="py-output">    |                 +- ClassDoc for epydoc_test.A.Nested [4]</span>
<span class="py-output">    |                    +- bases = []</span>
<span class="py-output">    |                    +- docstring = u'nested class'</span>
<span class="py-output">    |                    +- variables = {}</span>
<span class="py-output">    +- B =&gt; VariableDoc for epydoc_test.B [5]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.B [6]</span>
<span class="py-output">    |        +- bases</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.A [2] (defined above)</span>
<span class="py-output">    |        +- docstring = u'single base'</span>
<span class="py-output">    |        +- variables = {}</span>
<span class="py-output">    +- C =&gt; VariableDoc for epydoc_test.C [7]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.C [8]</span>
<span class="py-output">    |        +- bases</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.A [2] (defined above)</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.B [6] (defined above)</span>
<span class="py-output">    |        +- docstring = u'multiple bases'</span>
<span class="py-output">    |        +- variables = {}</span>
<span class="py-output">    +- D =&gt; VariableDoc for epydoc_test.D [9]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.D [10]</span>
<span class="py-output">    |        +- bases</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.A [2] (defined above)</span>
<span class="py-output">    |        +- docstring = u'extra parens around base'</span>
<span class="py-output">    |        +- variables = {}</span>
<span class="py-output">    +- E =&gt; VariableDoc for epydoc_test.E [11]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.E [12]</span>
<span class="py-output">    |        +- bases</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.A.Nested [4] (defined above)</span>
<span class="py-output">    |        +- docstring = u'dotted name'</span>
<span class="py-output">    |        +- variables = {}</span>
<span class="py-output">    +- F =&gt; VariableDoc for epydoc_test.F [13]</span>
<span class="py-output">    |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">    |  +- value</span>
<span class="py-output">    |     +- ClassDoc for epydoc_test.F [14]</span>
<span class="py-output">    |        +- bases</span>
<span class="py-output">    |        |  +- ClassDoc for epydoc_test.A.Nested [4] (defined above)</span>
<span class="py-output">    |        +- docstring = u'parens with dotted name'</span>
<span class="py-output">    |        +- variables = {}</span>
<span class="py-output">    +- Z =&gt; VariableDoc for epydoc_test.Z [15]</span>
<span class="py-output">       +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.Z [16]</span>
<span class="py-output">             +- bases = &lt;UNKNOWN&gt;</span>
<span class="py-output">             +- docstring = u'calculated base'</span>
<span class="py-output">             +- variables = {}</span></pre>
</blockquote>
<p>Base lists:</p>
</div>
<div class="section" id="delete-statements">
<h1>Delete Statements</h1>
<p>Deleting variables:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    x = y = 12</span>
<span class="py-more">... </span><span class="py-string">    del y</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value parse_repr is_alias'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- parse_repr = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- x =&gt; VariableDoc for epydoc_test.x [1]</span>
<span class="py-output">       +- is_alias = True</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- GenericValueDoc [2]</span>
<span class="py-output">             +- parse_repr = u'12'</span></pre>
</blockquote>
<p>The right-hand side of a <tt class="docutils literal"><span class="pre">del</span></tt> statement may contain a nested
combination of lists, tuples, and parenthases.  All variables found
anywhere in this nested structure should be deleted:</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    a=b=c=d=e=f=g=1</span>
<span class="py-more">... </span><span class="py-string">    del a</span>
<span class="py-more">... </span><span class="py-string">    del (b)</span>
<span class="py-more">... </span><span class="py-string">    del [c]</span>
<span class="py-more">... </span><span class="py-string">    del (d,)</span>
<span class="py-more">... </span><span class="py-string">    del (((e,)),)</span>
<span class="py-more">... </span><span class="py-string">    del [[[[f]]]]</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- g =&gt; VariableDoc for epydoc_test.g [1]</span>
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    a=b=c=d=e=f=g=1</span>
<span class="py-more">... </span><span class="py-string">    del a,b</span>
<span class="py-more">... </span><span class="py-string">    del (c,d)</span>
<span class="py-more">... </span><span class="py-string">    del [e,f]</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- g =&gt; VariableDoc for epydoc_test.g [1]</span>
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    a=b=c=d=e=f=g=1</span>
<span class="py-more">... </span><span class="py-string">    del ((a, (((((b, c)), d), [e]))), f)</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- g =&gt; VariableDoc for epydoc_test.g [1]</span></pre>
</blockquote>
<p>The right-hand side of a <tt class="docutils literal"><span class="pre">del</span></tt> statement may contain a dotted name, in
which case the named variable should be deleted from its containing
namespace.</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class A: a = b = 1</span>
<span class="py-more">... </span><span class="py-string">    del A.a</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value local_variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- A =&gt; VariableDoc for epydoc_test.A [1]</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.A [2]</span>
<span class="py-output">             +- variables</span>
<span class="py-output">                +- b =&gt; VariableDoc for epydoc_test.A.b [3]</span>
<span class="py-output">                   +- value</span>
<span class="py-output">                      +- GenericValueDoc [4]</span></pre>
</blockquote>
<p>If one of the variables to be deleted is expressed as anything other
than a simple identifier or a dotted name, then ignore it.  (In
particular, if we encounter 'del x[2]' then do not delete x.)</p>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    a = b = [1,2,3,4]</span>
<span class="py-more">... </span><span class="py-string">    del a[2]</span>
<span class="py-more">... </span><span class="py-string">    del a[2:]</span>
<span class="py-more">... </span><span class="py-string">    del ([b], a[1])</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- a =&gt; VariableDoc for epydoc_test.a [1]</span></pre>
</blockquote>
</div>
<div class="section" id="single-line-blocks">
<h1>Single-Line Blocks</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class A: 'docstring for A'</span>
<span class="py-more">...</span>
<span class="py-more">...</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value docstring'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- A =&gt; VariableDoc for epydoc_test.A [1]</span>
<span class="py-output">       +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.A [2]</span>
<span class="py-output">             +- docstring = u'docstring for A'</span>
<span class="py-output">             +- variables = {}</span></pre>
</blockquote>
</div>
<div class="section" id="imports">
<h1>Imports</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    import re</span>
<span class="py-more">... </span><span class="py-string">    from re import match</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value is_imported'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- match =&gt; VariableDoc for epydoc_test.match [1]</span>
<span class="py-output">    |  +- is_imported = True</span>
<span class="py-output">    |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">    +- re =&gt; VariableDoc for epydoc_test.re [2]</span>
<span class="py-output">       +- is_imported = True</span>
<span class="py-output">       +- value = &lt;UNKNOWN&gt;</span></pre>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    from re import match as much, split, sub as scuba</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables name imported_from'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- much =&gt; VariableDoc for epydoc_test.much [1]</span>
<span class="py-output">    |  +- imported_from = DottedName(u're', u'match')</span>
<span class="py-output">    |  +- name = u'much'</span>
<span class="py-output">    +- scuba =&gt; VariableDoc for epydoc_test.scuba [2]</span>
<span class="py-output">    |  +- imported_from = DottedName(u're', u'sub')</span>
<span class="py-output">    |  +- name = u'scuba'</span>
<span class="py-output">    +- split =&gt; VariableDoc for epydoc_test.split [3]</span>
<span class="py-output">       +- imported_from = DottedName(u're', u'split')</span>
<span class="py-output">       +- name = u'split'</span></pre>
</blockquote>
</div>
<div class="section" id="unicode">
<h1>Unicode</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    def f(x):</span>
<span class="py-more">... </span><span class="py-string">        u&quot;unicode in docstring: \u1000&quot;</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value docstring'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- f =&gt; VariableDoc for epydoc_test.f [1]</span>
<span class="py-output">       +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- RoutineDoc for epydoc_test.f [2]</span>
<span class="py-output">             +- docstring = u'unicode in docstring: \u1000'</span></pre>
</blockquote>
</div>
<div class="section" id="instance-variables">
<h1>Instance Variables</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class A:</span>
<span class="py-more">... </span><span class="py-string">        def __init__(self, x, y):</span>
<span class="py-more">... </span><span class="py-string">            self.x = 10</span>
<span class="py-more">...</span>
<span class="py-more">... </span><span class="py-string">            self.y = 20 #: docstring for y</span>
<span class="py-more">...</span>
<span class="py-more">... </span><span class="py-string">            self.z = 30</span>
<span class="py-more">... </span><span class="py-string">            '''docstring for z'''</span>
<span class="py-more">...</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value is_instvar docstring local_variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- A =&gt; VariableDoc for epydoc_test.A [1]</span>
<span class="py-output">       +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- is_instvar = &lt;UNKNOWN&gt;</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.A [2]</span>
<span class="py-output">             +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">             +- variables</span>
<span class="py-output">                +- __init__ =&gt; VariableDoc for epydoc_test.A.__init__ [3]</span>
<span class="py-output">                |  +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">                |  +- is_instvar = &lt;UNKNOWN&gt;</span>
<span class="py-output">                |  +- value</span>
<span class="py-output">                |     +- RoutineDoc for epydoc_test.A.__init__ [4]</span>
<span class="py-output">                |        +- docstring = &lt;UNKNOWN&gt;</span>
<span class="py-output">                +- y =&gt; VariableDoc for epydoc_test.A.y [5]</span>
<span class="py-output">                |  +- docstring = u'docstring for y'</span>
<span class="py-output">                |  +- is_instvar = True</span>
<span class="py-output">                |  +- value = &lt;UNKNOWN&gt;</span>
<span class="py-output">                +- z =&gt; VariableDoc for epydoc_test.A.z [6]</span>
<span class="py-output">                   +- docstring = u'docstring for z'</span>
<span class="py-output">                   +- is_instvar = True</span>
<span class="py-output">                   +- value = &lt;UNKNOWN&gt;</span></pre>
</blockquote>
</div>
<div class="section" id="assignments-into-namespaces">
<h1>Assignments Into Namespaces</h1>
<blockquote>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span>runparser(s=<span class="py-string">&quot;&quot;&quot;</span>
<span class="py-more">... </span><span class="py-string">    class A: pass</span>
<span class="py-more">... </span><span class="py-string">    A.x = 22</span>
<span class="py-more">... </span><span class="py-string">    &quot;&quot;&quot;</span>,
<span class="py-more">... </span>    attribs=<span class="py-string">'variables value local_variables'</span>)
<span class="py-output">ModuleDoc for epydoc_test [0]</span>
<span class="py-output"> +- variables</span>
<span class="py-output">    +- A =&gt; VariableDoc for epydoc_test.A [1]</span>
<span class="py-output">       +- value</span>
<span class="py-output">          +- ClassDoc for epydoc_test.A [2]</span>
<span class="py-output">             +- variables</span>
<span class="py-output">                +- x =&gt; VariableDoc for epydoc_test.A.x [3]</span>
<span class="py-output">                   +- value</span>
<span class="py-output">                      +- GenericValueDoc [4]</span></pre>
</blockquote>
</div>
</div>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
  <tr>
  <a class="nav" href="../index.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="../index.html">
    Home</a></td></a>
  <a class="nav" href="../installing.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="../installing.html">
    Installing Epydoc</a></td></a>
  <a class="nav" href="../using.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="../using.html">
    Using Epydoc</a></td></a>
  <a class="nav" href="../epytext.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="../epytext.html">
    Epytext</a></td></a>
  <td align="center" width="20%" class="nav">
    
    <A href="http://sourceforge.net/projects/epydoc"> 
    <IMG src="../sflogo.png" 
    width="88" height="26" border="0" alt="SourceForge"
    align="top"/></A></td>
    </tr>
</table>
</body>
</html>
